{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "cdf426de-3596-497d-8211-147b3ed16c59",
   "metadata": {},
   "source": [
    "# Designing Quantum Algorithms with Second Order Functions: A Flexible QPE"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3652b5a7-74ba-4b30-b267-fc544293fe0b",
   "metadata": {},
   "source": [
    "Quantum Phase Estimation (QPE) is a fundamental quantum function, at the core of the Shor, HHL, and amplitude estimation algorithms. QPE is a second order function, getting a quantum function $U$ and returning an estimation of its eigenvalues. (Recall that any quantum function represents a unitary matrix.) A QPE that encodes the eigenvalues on $m$ qubits involves a series of $m$ controlled operations of $U^{2^k}$ with $0\\leq k < m-1$. This quantum advantage based on the QPE function relies on an ability to implement the power of a given unitary $U$ efficiently. Otherwise, naive $U$ is called $\\sum^{m-1}_{k=0} 2^k=2^m$ times &ndash; a number \n",
    "that is exponential in the number of qubits.\n",
    "\n",
    "**This tutorial shows how to leverage declarative and programmatic modeling for exploring the QPE function in the context of Hamiltonian simulation.**"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c631a19f-3b96-4855-bb75-4a3802dcbe80",
   "metadata": {},
   "source": [
    "Start with basic imports:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "4bd92808-4b4e-4b0e-934c-f8afc6d65b3f",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-05-07T14:27:52.168409Z",
     "iopub.status.busy": "2024-05-07T14:27:52.167925Z",
     "iopub.status.idle": "2024-05-07T14:27:55.071425Z",
     "shell.execute_reply": "2024-05-07T14:27:55.070776Z"
    }
   },
   "outputs": [],
   "source": [
    "from classiq import CArray, CInt, CReal, QArray, QBit, QCallable, qfunc"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d5a1f97d-7694-4033-b574-4e3b74ab1944",
   "metadata": {},
   "source": [
    "## 1. Defining a Flexible QPE\n",
    "\n",
    "Define a flexible QPE function. Instead of getting a single operand $U$, it gets a parametric operand, $U(p)$, where $p$ is an integer such that $U(p)\\equiv U^p$. That is, the power logic of $U$ passes explicitly with the function. In addition, the QPE itself has an integer parameter for the phase register size."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "11152bd2-fb6f-44dc-9bb0-e1bc9550a721",
   "metadata": {},
   "source": [
    "<center>\n",
    "<img src=\"https://docs.classiq.io/resources/qpe_flexible.png\" style=\"width:95%\">\n",
    "<figcaption align = \"middle\"> A Flexible QPE, a rolled-up (left) and a rolled-down (right) layouts. </figcaption>\n",
    "</center>"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "8c1a034a-bd7e-4c33-8788-ff983bed211a",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-05-07T14:27:55.074762Z",
     "iopub.status.busy": "2024-05-07T14:27:55.073918Z",
     "iopub.status.idle": "2024-05-07T14:27:55.078813Z",
     "shell.execute_reply": "2024-05-07T14:27:55.078241Z"
    }
   },
   "outputs": [],
   "source": [
    "from classiq import H, apply_to_all, control, invert, qft, repeat\n",
    "\n",
    "\n",
    "@qfunc\n",
    "def my_qpe_flexible(\n",
    "    unitary: QCallable[CInt, QArray[QBit]],\n",
    "    state: QArray[QBit],\n",
    "    phase: QArray[QBit],\n",
    ") -> None:\n",
    "    apply_to_all(H, phase)\n",
    "\n",
    "    repeat(\n",
    "        count=phase.len,\n",
    "        iteration=lambda index: control(\n",
    "            ctrl=phase[index],\n",
    "            operand=lambda: unitary(2**index, state),\n",
    "        ),\n",
    "    )\n",
    "\n",
    "    invert(\n",
    "        lambda: qft(phase),\n",
    "    )"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fc463a31-6837-4b99-b5e3-6c527bf1dad7",
   "metadata": {},
   "source": [
    "## 2. Example QPE for Finding the Eigenvalues of an Hermitian Matrix\n",
    "\n",
    "One use of the QPE is to find the eigenvalues of a given Hermitian matrix $H$. Canonical use cases: (a) the HHL algorithm for solving linear equations $H\\cdot \\vec{x}=\\vec{b}$, where the matrix eigenvalues need to be stored on a quantum register, and (b) finding the minimal energy of a molecule Hamiltonian $H$, preparing an initial guess for an eigenvector followed by a QPE that aims to detect the minimal eigenvalue.\n",
    "\n",
    "In both use cases, a QPE is performed on *Hamiltonian evolution* $U=e^{2\\pi i H}$."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d13ea2c2",
   "metadata": {},
   "source": [
    "### 2.1 Hamiltonian Evolution\n",
    "\n",
    "Hamiltonian evolution, or Hamiltonian simulation, is one of the promising uses of quantum computers, where the advantage over classical approaches is clear and transparent (as proposed by Richard Feynman in 1982). Nevertheless, constructing a quantum program for efficient Hamiltonian dynamics is not an easy task. The most common examples use approximated product formulas such as the Trotter-Suzuki (TS) formulas.\n",
    "\n",
    "#### 2.1.1 Trotter-Suzuki of Order 1\n",
    "\n",
    "Write the Hamiltonian as a sum of Pauli strings $H=\\sum_{i=0}^{L-1} a^{(k)} P^{(k)}$,\n",
    "where $a^{(k)}$ are complex coefficients, and each of $P^{(k)}$ is a Pauli string of the form $s_0\\otimes s_1\\otimes\\dots\\otimes s_L$, with $s_i\\in \\{I, X, Y, Z\\}$. Approximating Hamiltonian simulation with TS of order 1 refers to:\n",
    "$$\n",
    "e^{2\\pi i H}\\approx \\left(\\Pi^{L-1}_{i=0}e^{\\frac{a^{(k)}}{r} P^{(k)}}\\right)^r,\n",
    "$$\n",
    "where $r$ is called the *number of repetitions*.\n",
    "\n",
    "* *Given a Hamiltonian and a functional error $\\epsilon$, what is the required number of repetitions?*\n",
    "\n",
    "Apparently, this is not easy to answer. The literature provides several bounds for the number of repetitions for a given functional error and error metric; however, typically, these bounds are very rough, far from representing the actual number of repetitions to use. See Ref.[[1](#Errors)] for a comprehensive study.\n",
    "\n",
    "* *When performing a QPE, the challenge is even more pronounced*:\n",
    "\n",
    "\n",
    "For the QPE, a series of Hamiltonian simulations with an exponentially growing evolution coefficient, $e^{2\\pi i H}, \\, e^{2^1 2\\pi i H}, \\, e^{2^2 2\\pi i H}, \\dots, e^{2^{m-1}2\\pi i H}$, is required. Which product formula to use for each step, assuming you keep the same error per step?\n",
    "\n",
    "Lacking good theoretical bounds for the aforementioned questions, resort to experimental exploration in the hope of finding theoretical clues and insights:"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1db1487a-caea-4a7c-a9df-eb19b42ccc5d",
   "metadata": {},
   "source": [
    "#### 2.1.2 A Flexible TS for Plugging into the Flexible QPE\n",
    "\n",
    "The Trotter-Suzuki of order 1 function, $\\text{TS}_1$, gets an Hamiltonian $H$, evolution coefficient $t$, and repetition $r$. Define a wrapper function:\n",
    "\n",
    "$$\n",
    "\\tilde{\\text{TS}}_1\\left(H,t,p \\right) := \\text{TS}_1\\left(H,pt,r=f(p)\\right).\n",
    "$$\n",
    "\n",
    "The function $f(p)$ tries to capture how many repetitions can approximate $\\left(e^{2\\pi i H}\\right)^p=e^{p 2\\pi i H}$. Section 2.2 defines the \"goodness of approximation\".\n",
    "\n",
    "\n",
    "Define ansatz for the repetition scaling $f(p)$:\n",
    "\\begin{equation}\n",
    "f(p)\\equiv \\left\\{\n",
    "\\begin{array}{l l}\n",
    "r_0 & \\text{if  } p<p_0,  \\\\       \n",
    "r_0 \\left\\lceil {\\left(p/p_0\\right)^\\gamma}\\right\\rceil & \\text{if  } p\\geq p_0\n",
    "\\end{array}\n",
    "\\right. , \n",
    "\\end{equation}\n",
    "where $r_0$, $p_0$, and $\\gamma$ are parameters to tune."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "6418ed47-719d-4bd7-bac9-bed4c0b1c77c",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-05-07T14:27:55.081339Z",
     "iopub.status.busy": "2024-05-07T14:27:55.080916Z",
     "iopub.status.idle": "2024-05-07T14:27:55.084988Z",
     "shell.execute_reply": "2024-05-07T14:27:55.084424Z"
    }
   },
   "outputs": [],
   "source": [
    "from classiq import suzuki_trotter\n",
    "from classiq.qmod.symbolic import Piecewise, ceiling\n",
    "\n",
    "\n",
    "def suzuki_trotter_with_power_logic(\n",
    "    hamiltonian,\n",
    "    pw: CInt,\n",
    "    evolution_coefficient: CReal,\n",
    "    order: CInt,\n",
    "    target: QArray[QBit],\n",
    "    p_0: int,\n",
    "    gamma: float,\n",
    "    r0: int,\n",
    ") -> None:\n",
    "    suzuki_trotter(\n",
    "        hamiltonian,\n",
    "        evolution_coefficient=evolution_coefficient * pw,\n",
    "        order=1,\n",
    "        repetitions=Piecewise(\n",
    "            (r0, pw < p_0), (ceiling(r0 * (pw / p_0) ** gamma), True)\n",
    "        ),\n",
    "        qbv=target,\n",
    "    )"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "359439f2-ca88-42e7-a554-4d14991139d7",
   "metadata": {},
   "source": [
    "### 2.2 QPE Performance\n",
    "\n",
    "In this tutorial, the measure for goodness of approximation refers to the functionality of the full QPE function, rather than taking a rigorous operator norm per each Hamiltonian simulation step in the QPE. Ways of examining the approximated QPE:\n",
    "1. By its ability to approximate an eigenvalue for a given eigenvector.\n",
    "2. By comparing its resulting phase state with the one that results from a QPE with an exact Hamiltonian evolution, using a swap test.\n",
    "  \n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3d7b255f-a838-48b1-abbb-26670b517793",
   "metadata": {},
   "source": [
    "## 3. Exploring a Specific Example"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9c340661-399d-4b6f-a5af-5aaedf19d9fa",
   "metadata": {},
   "source": [
    "Consider a specific Hamiltonian defined with the `PauliOperator` object"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "3328ee05-30e7-4136-9e50-30ce3b70c5dd",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-05-07T14:27:55.087742Z",
     "iopub.status.busy": "2024-05-07T14:27:55.087567Z",
     "iopub.status.idle": "2024-05-07T14:27:55.091929Z",
     "shell.execute_reply": "2024-05-07T14:27:55.091329Z"
    }
   },
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "from classiq.applications.chemistry import PauliOperator\n",
    "\n",
    "paulis = [\n",
    "    (\"II\", 0.4),\n",
    "    (\"IZ\", -0.05),\n",
    "    (\"IX\", -0.03),\n",
    "    (\"ZZ\", -0.06),\n",
    "    (\"XZ\", 0.04),\n",
    "    (\"XX\", -0.16),\n",
    "    (\"YY\", -0.06),\n",
    "]\n",
    "\n",
    "po = PauliOperator(pauli_list=paulis)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8ac801f2-af6e-48e4-a5aa-2e2f1796c620",
   "metadata": {},
   "source": [
    "Define auxiliary functions for parsing the PauliOperator object."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "3b431cad",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-05-07T14:27:55.094066Z",
     "iopub.status.busy": "2024-05-07T14:27:55.093895Z",
     "iopub.status.idle": "2024-05-07T14:27:55.097748Z",
     "shell.execute_reply": "2024-05-07T14:27:55.097150Z"
    }
   },
   "outputs": [],
   "source": [
    "from typing import cast\n",
    "\n",
    "from classiq import Pauli, PauliTerm\n",
    "\n",
    "my_list = {\"I\": Pauli.I, \"X\": Pauli.X, \"Y\": Pauli.Y, \"Z\": Pauli.Z}\n",
    "\n",
    "\n",
    "def pauli_str_to_enums(pauli):\n",
    "    return [my_list[s] for s in pauli]\n",
    "\n",
    "\n",
    "def pauli_operator_to_hamiltonian(pauli_operator):\n",
    "    return [\n",
    "        PauliTerm(\n",
    "            pauli=pauli_str_to_enums(pauli), coefficient=cast(complex, coeff).real\n",
    "        )\n",
    "        for pauli, coeff in pauli_operator.pauli_list\n",
    "    ]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3f30bd12-ecc8-4cbe-ac9f-9f20979c2080",
   "metadata": {},
   "source": [
    "For the demonstration, choose one of the eigenvectors of the matrix, and test the result of the approximated QPE with respect to the expected eigenvalue."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "ecee46f9-3200-4d8a-a0d0-c020918d6bb6",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-05-07T14:27:55.100107Z",
     "iopub.status.busy": "2024-05-07T14:27:55.099677Z",
     "iopub.status.idle": "2024-05-07T14:27:55.104710Z",
     "shell.execute_reply": "2024-05-07T14:27:55.104059Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "chosen eigenvector: [0.54233721 0.48935737 0.47765123 0.4881076 ]\n",
      "the eigenvalue to estimate: 0.2096699009257637\n"
     ]
    }
   ],
   "source": [
    "a_mat = po.to_matrix().real\n",
    "w, v = np.linalg.eig(a_mat)\n",
    "\n",
    "chosen_eig = 2\n",
    "print(\"chosen eigenvector:\", v[:, chosen_eig])\n",
    "print(\"the eigenvalue to estimate:\", w[chosen_eig])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f9fe49c0-81ee-4f42-827d-b26c3aa18c11",
   "metadata": {},
   "source": [
    "***\n",
    "*Note: For this example, the most naive upper bound for TS formula of order 1 and error $\\epsilon=0.1$ (defined by a spectral norm) gives $r=O(4t^2)$ [[2](#TS)], with $t=2\\pi$ for the first QPE step. This corresponds to $r_0\\sim 160$, and the following QPE steps grow exponentially $r_k\\sim 160\\times 4^k$. The result is a huge circuit depth, which you can relax by tuning the parameters of the ansatz.*\n",
    "\n",
    "*Tighter bounds based on commutation relations[[1](#Errors)] can give more reasonable numbers. However, the main purpose of this tutorial is to highlight the advantages of abstract, high-level modeling. Indeed, any known bound can be incorporated in the flexible Trotter-Suzuki by defining $f(m)$ accordingly.*\n",
    "***"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2b44ed21-bd14-4bd4-9851-95f9b3c9dde8",
   "metadata": {},
   "source": [
    "### 3.1. Eigenvalue Estimation\n",
    "\n",
    "Choose parameters for the power-logic function $f(p)$, construct and synthesize a model, and visualize the resulting quantum program."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "eee53fb1-209b-45b6-be3a-a5e18108a695",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-05-07T14:27:55.106988Z",
     "iopub.status.busy": "2024-05-07T14:27:55.106647Z",
     "iopub.status.idle": "2024-05-07T14:28:01.489888Z",
     "shell.execute_reply": "2024-05-07T14:28:01.489243Z"
    }
   },
   "outputs": [],
   "source": [
    "from classiq import Output, allocate, create_model, prepare_amplitudes, synthesize\n",
    "\n",
    "QPE_SIZE = 5\n",
    "p_0 = 2 ** (QPE_SIZE - 3)\n",
    "R0 = 4  # according to the naive bound this should be O(150)\n",
    "GAMMA = 1.5  # according to the naive bound this should be 4\n",
    "\n",
    "\n",
    "@qfunc\n",
    "def main(phase_approx: Output[QArray[QBit, QPE_SIZE]]) -> None:\n",
    "    state = QArray(\"state\")\n",
    "    allocate(QPE_SIZE, phase_approx)\n",
    "    prepare_amplitudes(v[:, chosen_eig].tolist(), 0.0, state)\n",
    "    my_qpe_flexible(\n",
    "        unitary=lambda pw, target: suzuki_trotter_with_power_logic(\n",
    "            hamiltonian=pauli_operator_to_hamiltonian(po),\n",
    "            pw=pw,\n",
    "            evolution_coefficient=-2 * np.pi,\n",
    "            order=1,\n",
    "            r0=R0,\n",
    "            p_0=p_0,\n",
    "            gamma=GAMMA,\n",
    "            target=target,\n",
    "        ),\n",
    "        state=state,\n",
    "        phase=phase_approx,\n",
    "    )\n",
    "\n",
    "\n",
    "quantum_program = synthesize(create_model(main))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "360823dd-ad1f-4559-801d-2aecaa0bee7b",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-05-07T14:28:01.492640Z",
     "iopub.status.busy": "2024-05-07T14:28:01.492244Z",
     "iopub.status.idle": "2024-05-07T14:28:01.564066Z",
     "shell.execute_reply": "2024-05-07T14:28:01.563359Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Opening: https://platform.classiq.io/circuit/4bdc4818-69a2-4251-ad95-964baad6b2a5?version=0.41.0.dev39%2B79c8fd0855\n"
     ]
    }
   ],
   "source": [
    "from classiq import show\n",
    "\n",
    "show(quantum_program)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e0477e34",
   "metadata": {},
   "source": [
    "Execute the quantum program and examine the results: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "92383122-e6c3-45bf-bd8a-afb484b703e1",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-05-07T14:28:01.566718Z",
     "iopub.status.busy": "2024-05-07T14:28:01.566253Z",
     "iopub.status.idle": "2024-05-07T14:28:03.896005Z",
     "shell.execute_reply": "2024-05-07T14:28:03.895287Z"
    }
   },
   "outputs": [],
   "source": [
    "from classiq import execute\n",
    "\n",
    "result = execute(quantum_program).result()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "cbb6d34e-1638-4b8e-8f8c-e4c5758434e5",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-05-07T14:28:03.900268Z",
     "iopub.status.busy": "2024-05-07T14:28:03.899100Z",
     "iopub.status.idle": "2024-05-07T14:28:03.904879Z",
     "shell.execute_reply": "2024-05-07T14:28:03.904257Z"
    }
   },
   "outputs": [],
   "source": [
    "parsed_counts = result[0].value.parsed_counts\n",
    "phase_counts = {\n",
    "    sampled_state.state[\"phase_approx\"] / (2**QPE_SIZE): sampled_state.shots\n",
    "    for sampled_state in parsed_counts\n",
    "}"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "eedb7fc6-7025-4f2e-8175-074a3067d333",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-05-07T14:28:03.909080Z",
     "iopub.status.busy": "2024-05-07T14:28:03.907999Z",
     "iopub.status.idle": "2024-05-07T14:28:04.240898Z",
     "shell.execute_reply": "2024-05-07T14:28:04.240169Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "exact eigenvalue: 0.2096699009257637\n",
      "approximated eigenvalue: 0.21875\n"
     ]
    },
    {
     "data": {
      "image/png": "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DodDDocjYl96enpPTtHmdDr55u5FrHfvYr17F+vd+1jz3nUp6+1yuS7pa8Xkk2TT0tI0duxYVVZW2vva2tpUWVkpr9cbiykBAACDxOxHPCUlJSouLta4ceM0fvx4rV69WufOnbPf1QMAAC5fMQuU+++/X6dOndLixYsVCAR00003adeuXXK73bGaUgSHw6ElS5Z0+NESegbr3btY797Fevc+1rx39cR6J1nWpbzXBwAAoPfw24wBAIBxCBQAAGAcAgUAABiHQAEAAMa5rANl7dq1Gj58uPr27au8vDy99dZbf3P8tm3bNHLkSPXt21ejR4/Wyy+/3EszTQzRrPdzzz2n2267TYMHD9bgwYOVn5//uf99ECna7+92W7duVVJSku69996enWCCiXa9Gxoa5PP5lJWVJYfDoeuuu46/U6IQ7XqvXr1a119/vfr166ecnBzNmzdP58+f76XZxrfXX39dd999t7Kzs5WUlKQXX3zxc8957bXXdPPNN8vhcOiLX/yiNm7cGP0dd89v14k/W7dutdLS0qyf//zn1pEjR6yHH37YSk9Pt4LB4EXHv/nmm1ZKSoq1cuVK6+jRo9aiRYusPn36WIcPH+7lmcenaNf7W9/6lrV27VrrnXfesY4dO2Y99NBDlsvlsj788MNennl8ina92504ccL6whe+YN12223WPffc0zuTTQDRrndjY6M1btw4684777R++9vfWidOnLBee+0169ChQ7088/gU7Xpv3rzZcjgc1ubNm60TJ05Yu3fvtrKysqx58+b18szj08svv2w9+uij1gsvvGBJsrZv3/43xx8/ftzq37+/VVJSYh09etR65plnrJSUFGvXrl1R3e9lGyjjx4+3fD6ffbu1tdXKzs62li9fftHx9913n1VYWBixLy8vz/rnf/7nHp1nooh2vS/U0tJiDRo0yNq0aVNPTTGhdGa9W1parFtuucX6j//4D6u4uJhAiUK0671+/Xrr6quvtpqamnprigkl2vX2+XzW7bffHrGvpKTEmjhxYo/OMxFdSqA88sgj1g033BCx7/7777cKCgqiuq/L8kc8TU1NqqqqUn5+vr0vOTlZ+fn58vv9Fz3H7/dHjJekgoKCzxyPT3VmvS/08ccfq7m5WRkZGT01zYTR2fVeunSpMjMzNWPGjN6YZsLozHr/+te/ltfrlc/nk9vt1o033qhly5aptbW1t6Ydtzqz3rfccouqqqrsHwMdP35cL7/8su68885emfPlprseL+Pitxl3tz//+c9qbW3t8Km1brdb77777kXPCQQCFx0fCAR6bJ6JojPrfaEFCxYoOzu7wzc9OurMev/2t7/V888/r0OHDvXCDBNLZ9b7+PHjevXVVzVt2jS9/PLLev/99/X9739fzc3NWrJkSW9MO251Zr2/9a1v6c9//rNuvfVWWZallpYWfe9739OPf/zj3pjyZeezHi/D4bD+7//+T/369bukr3NZPoOC+LJixQpt3bpV27dvV9++fWM9nYRz5swZTZ8+Xc8995yuuOKKWE/nstDW1qbMzEw9++yzGjt2rO6//349+uijKisri/XUEtJrr72mZcuWad26dfrd736nF154QTt27NATTzwR66nhb7gsn0G54oorlJKSomAwGLE/GAzK4/Fc9ByPxxPVeHyqM+vd7qmnntKKFSu0Z88ejRkzpienmTCiXe8//vGP+uCDD3T33Xfb+9ra2iRJqampqq6u1jXXXNOzk45jnfn+zsrKUp8+fZSSkmLvGzVqlAKBgJqampSWltajc45nnVnvxx57TNOnT9d3v/tdSdLo0aN17tw5zZw5U48++qiSk/l/9e70WY+XTqfzkp89kS7TZ1DS0tI0duxYVVZW2vva2tpUWVkpr9d70XO8Xm/EeEmqqKj4zPH4VGfWW5JWrlypJ554Qrt27dK4ceN6Y6oJIdr1HjlypA4fPqxDhw7Z2z/8wz/o61//ug4dOqScnJzenH7c6cz398SJE/X+++/bIShJf/jDH5SVlUWcfI7OrPfHH3/cIULa49Di19F1u257vIzu9buJY+vWrZbD4bA2btxoHT161Jo5c6aVnp5uBQIBy7Isa/r06dbChQvt8W+++aaVmppqPfXUU9axY8esJUuW8DbjKES73itWrLDS0tKsX/3qV9bJkyft7cyZM7G6hLgS7XpfiHfxRCfa9a6pqbEGDRpkzZ4926qurrbKy8utzMxM68knn4zVJcSVaNd7yZIl1qBBg6z/+q//so4fP2698sor1jXXXGPdd999sbqEuHLmzBnrnXfesd555x1LkvX0009b77zzjvWnP/3JsizLWrhwoTV9+nR7fPvbjOfPn28dO3bMWrt2LW8zjtYzzzxjDRs2zEpLS7PGjx9v7d+/3z721a9+1SouLo4Y/8tf/tK67rrrrLS0NOuGG26wduzY0cszjm/RrPdVV11lSeqwLVmypPcnHqei/f7+awRK9KJd73379ll5eXmWw+Gwrr76autf//VfrZaWll6edfyKZr2bm5utxx9/3Lrmmmusvn37Wjk5Odb3v/996y9/+UvvTzwO/eY3v7no38fta1xcXGx99atf7XDOTTfdZKWlpVlXX321tWHDhqjvN8myeH4LAACY5bJ8DQoAADAbgQIAAIxDoAAAAOMQKAAAwDgECgAAMA6BAgAAjEOgAAAA4xAoAADAOAQKAAAwDoECAACMQ6AAAADjECgAAMA4/w9yyf/H9o81WgAAAABJRU5ErkJggg==",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "\n",
    "plt.bar(phase_counts.keys(), phase_counts.values(), width=0.01)\n",
    "most_probable_phase = max(phase_counts, key=phase_counts.get)\n",
    "plt.plot(w[chosen_eig], phase_counts[most_probable_phase], \"or\")\n",
    "print(\"exact eigenvalue:\", w[chosen_eig])\n",
    "print(\"approximated eigenvalue:\", most_probable_phase)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3be110cf",
   "metadata": {},
   "source": [
    "Indeed, the approximated Hamiltonian simulation seems to be sufficient to find the eigenvalue."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e2efc809-9f15-43f5-bb58-00e7ae9a6993",
   "metadata": {},
   "source": [
    "### 3.2. QPE State with Exact Hamiltonian Simulation Versus Approximated"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "15a5e2f9-480d-4db5-8789-44e7c29b0b14",
   "metadata": {},
   "source": [
    "Define the following quantum function: an exact Hamiltonian simulation with power-logic. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "d2fd3665-db89-4a03-ab56-e6174b62eba1",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-05-07T14:28:04.245963Z",
     "iopub.status.busy": "2024-05-07T14:28:04.244763Z",
     "iopub.status.idle": "2024-05-07T14:28:04.251585Z",
     "shell.execute_reply": "2024-05-07T14:28:04.250911Z"
    }
   },
   "outputs": [],
   "source": [
    "from typing import List\n",
    "\n",
    "from classiq import power, unitary\n",
    "\n",
    "\n",
    "@qfunc\n",
    "def unitary_with_power_logic(\n",
    "    pw: CInt, matrix: CArray[CArray[CReal]], target: QArray[QBit]\n",
    ") -> None:\n",
    "    power(pw, lambda: unitary(elements=matrix, target=target))"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0739244f",
   "metadata": {},
   "source": [
    "Continue with the same parameters from above for $f(p)$. Construct a model that calls two QPEs in parallel; one with an approximated Hamiltonian simulation and the other with an exact one. Finally, perform a swap test between the resulting phases. Synthesize the model and visualize the resulting quantum program."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "206797bd-d14c-4b31-9774-31674fe8a423",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-05-07T14:28:04.256305Z",
     "iopub.status.busy": "2024-05-07T14:28:04.255147Z",
     "iopub.status.idle": "2024-05-07T14:28:13.770405Z",
     "shell.execute_reply": "2024-05-07T14:28:13.769415Z"
    }
   },
   "outputs": [],
   "source": [
    "import scipy\n",
    "\n",
    "from classiq import swap_test\n",
    "\n",
    "\n",
    "@qfunc\n",
    "def main(test: Output[QBit]) -> None:\n",
    "    state = QArray(\"state\")\n",
    "    phase_approx = QArray(\"phase_approx\")\n",
    "    phase_exact = QArray(\"phase_exact\")\n",
    "    allocate(QPE_SIZE, phase_approx)\n",
    "    allocate(QPE_SIZE, phase_exact)\n",
    "    prepare_amplitudes(v[:, chosen_eig].tolist(), 0.0, state)\n",
    "    my_qpe_flexible(\n",
    "        unitary=lambda pw, target: suzuki_trotter_with_power_logic(\n",
    "            hamiltonian=pauli_operator_to_hamiltonian(po),\n",
    "            pw=pw,\n",
    "            evolution_coefficient=-2 * np.pi,\n",
    "            order=1,\n",
    "            r0=R0,\n",
    "            p_0=p_0,\n",
    "            gamma=GAMMA,\n",
    "            target=target,\n",
    "        ),\n",
    "        state=state,\n",
    "        phase=phase_approx,\n",
    "    )\n",
    "    my_qpe_flexible(\n",
    "        unitary=lambda arg0, arg1: unitary_with_power_logic(\n",
    "            matrix=scipy.linalg.expm(2 * np.pi * 1j * po.to_matrix()).tolist(),\n",
    "            pw=arg0,\n",
    "            target=arg1,\n",
    "        ),\n",
    "        state=state,\n",
    "        phase=phase_exact,\n",
    "    )\n",
    "\n",
    "    swap_test(state1=phase_exact, state2=phase_approx, test=test)\n",
    "\n",
    "\n",
    "quantum_program = synthesize(create_model(main))"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "bef6673c-fafd-4230-8aac-4dc2110c2224",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-05-07T14:28:13.782221Z",
     "iopub.status.busy": "2024-05-07T14:28:13.781780Z",
     "iopub.status.idle": "2024-05-07T14:28:14.025910Z",
     "shell.execute_reply": "2024-05-07T14:28:14.025203Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Opening: https://platform.classiq.io/circuit/ec0a19cb-3d19-4ca6-ba09-7d519d85559e?version=0.41.0.dev39%2B79c8fd0855\n"
     ]
    }
   ],
   "source": [
    "show(quantum_program)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0ef3f54f",
   "metadata": {},
   "source": [
    "Execute and examine the results."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "98ed6512-ad5b-4602-bf23-a13636dbbbe1",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-05-07T14:28:14.031912Z",
     "iopub.status.busy": "2024-05-07T14:28:14.030236Z",
     "iopub.status.idle": "2024-05-07T14:28:16.571806Z",
     "shell.execute_reply": "2024-05-07T14:28:16.571186Z"
    }
   },
   "outputs": [],
   "source": [
    "result = execute(quantum_program).result()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "id": "444c347e-9078-40e2-a8d8-c25a80b1d58f",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-05-07T14:28:16.574678Z",
     "iopub.status.busy": "2024-05-07T14:28:16.574205Z",
     "iopub.status.idle": "2024-05-07T14:28:16.577364Z",
     "shell.execute_reply": "2024-05-07T14:28:16.576734Z"
    }
   },
   "outputs": [],
   "source": [
    "test_counts = result[0].value.counts"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d87f7376-ff60-4933-9ffb-8cd3422ffe14",
   "metadata": {},
   "source": [
    "The overlap between the two input states of the swap test, $\\psi_1$, $\\psi_2$, is given by\n",
    "$$\n",
    "Prob(\\text{test qubit at state } |0\\rangle) = \\frac{1}{2}\\left(\n",
    "1+\\left|\\langle \\psi_1 |\\psi_2\\rangle\\right|^2\\right)\n",
    "$$"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "7a242cf3-5b27-4c90-942d-5ea3a56b26f5",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2024-05-07T14:28:16.580116Z",
     "iopub.status.busy": "2024-05-07T14:28:16.579605Z",
     "iopub.status.idle": "2024-05-07T14:28:16.583398Z",
     "shell.execute_reply": "2024-05-07T14:28:16.582843Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Fidelity (overlap): 0.948\n"
     ]
    }
   ],
   "source": [
    "print(\"Fidelity (overlap):\", 2 * test_counts[\"0\"] / sum(test_counts.values()) - 1)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d404f85d",
   "metadata": {},
   "source": [
    "The results are good. You can try to reduce the $r_0$ and/or $\\gamma$ parameters, and experimentally study the relation between the functional error and circuit depth."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6d6d68a2-77a8-4c97-8c92-b162c8636a21",
   "metadata": {},
   "source": [
    "## 4. Comment\n",
    "\n",
    "* This tutorial focused on the Trotter-Suzuki formula of order 1 for approximating the Hamiltonian simulation. You can test other implementations, including their \"power-logic\", such as higher order TS formulas, qDRIFT, or a combination of TS and qDRIFT."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7fb5f96c-4f10-4b94-a6e9-2f610dd48d8c",
   "metadata": {},
   "source": [
    "## References\n",
    "\n",
    "<a name='Errors'>[1]</a>: [Childs, Andrew M., et al. Theory of Trotter error with commutator scaling. PRX 11 (2021): 011020.](https://journals.aps.org/prx/abstract/10.1103/PhysRevX.11.011020)\n",
    "\n",
    "<a name='TS'>[2]</a>: [Childs, Andrew M., et al. Toward the first quantum simulation with quantum speedup. PNAS 115 9456 (2018).](https://www.pnas.org/doi/abs/10.1073/pnas.1801723115)\n"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}
